home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / perl / 5.10.0 / ExtUtils / MakeMaker / Tutorial.pod < prev    next >
Encoding:
Text File  |  2009-06-26  |  4.3 KB  |  182 lines
  1. package ExtUtils::MakeMaker::Tutorial;
  2.  
  3. use vars qw($VERSION);
  4. $VERSION = 0.02;
  5.  
  6.  
  7. =head1 NAME
  8.  
  9. ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker
  10.  
  11. =head1 SYNOPSIS
  12.  
  13.     use ExtUtils::MakeMaker;
  14.  
  15.     WriteMakefile(
  16.         NAME            => 'Your::Module',
  17.         VERSION_FROM    => 'lib/Your/Module.pm'
  18.     );
  19.  
  20. =head1 DESCRIPTION
  21.  
  22. This is a short tutorial on writing a simple module with MakeMaker.
  23. Its really not that hard.
  24.  
  25.  
  26. =head2 The Mantra
  27.  
  28. MakeMaker modules are installed using this simple mantra
  29.  
  30.         perl Makefile.PL
  31.         make
  32.         make test
  33.         make install
  34.  
  35. There are lots more commands and options, but the above will do it.
  36.  
  37.  
  38. =head2 The Layout
  39.  
  40. The basic files in a module look something like this.
  41.  
  42.         Makefile.PL
  43.         MANIFEST
  44.         lib/Your/Module.pm
  45.  
  46. That's all that's strictly necessary.  There's additional files you might
  47. want:
  48.  
  49.         lib/Your/Other/Module.pm
  50.         t/some_test.t
  51.         t/some_other_test.t
  52.         Changes
  53.         README
  54.         INSTALL
  55.         MANIFEST.SKIP
  56.         bin/some_program
  57.  
  58. =over 4
  59.  
  60. =item Makefile.PL
  61.  
  62. When you run Makefile.PL, it makes a Makefile.  That's the whole point of
  63. MakeMaker.  The Makefile.PL is a simple program which loads
  64. ExtUtils::MakeMaker and runs the WriteMakefile() function to generate a
  65. Makefile.
  66.  
  67. Here's an example of what you need for a simple module:
  68.  
  69.     use ExtUtils::MakeMaker;
  70.  
  71.     WriteMakefile(
  72.         NAME            => 'Your::Module',
  73.         VERSION_FROM    => 'lib/Your/Module.pm'
  74.     );
  75.  
  76. NAME is the top-level namespace of your module.  VERSION_FROM is the file
  77. which contains the $VERSION variable for the entire distribution.  Typically
  78. this is the same as your top-level module.
  79.  
  80.  
  81. =item MANIFEST
  82.  
  83. A simple listing of all the files in your distribution.
  84.  
  85.         Makefile.PL
  86.         MANIFEST
  87.         lib/Your/Module.pm
  88.  
  89. File paths in a MANIFEST always use Unix conventions (ie. /) even if you're
  90. not on Unix.
  91.  
  92. You can write this by hand or generate it with 'make manifest'.
  93.  
  94. See L<ExtUtils::Manifest> for more details.
  95.  
  96.  
  97. =item lib/
  98.  
  99. This is the directory where your .pm and .pod files you wish to have
  100. installed go.  They are layed out according to namespace.  So Foo::Bar
  101. is F<lib/Foo/Bar.pm>.
  102.  
  103.  
  104. =item t/
  105.  
  106. Tests for your modules go here.  Each test filename ends with a .t.
  107. So F<t/foo.t>/  'make test' will run these tests.  The directory is flat,
  108. you cannot, for example, have t/foo/bar.t run by 'make test'.
  109.  
  110. Tests are run from the top level of your distribution.  So inside a test
  111. you would refer to ./lib to enter the lib directory, for example.
  112.  
  113.  
  114. =item Changes
  115.  
  116. A log of changes you've made to this module.  The layout is free-form.
  117. Here's an example:
  118.  
  119.     1.01 Fri Apr 11 00:21:25 PDT 2003
  120.         - thing() does some stuff now
  121.         - fixed the wiggy bug in withit()
  122.  
  123.     1.00 Mon Apr  7 00:57:15 PDT 2003
  124.         - "Rain of Frogs" now supported
  125.  
  126.  
  127. =item README
  128.  
  129. A short description of your module, what it does, why someone would use it
  130. and its limitations.  CPAN automatically pulls your README file out of
  131. the archive and makes it available to CPAN users, it is the first thing
  132. they will read to decide if your module is right for them.
  133.  
  134.  
  135. =item INSTALL
  136.  
  137. Instructions on how to install your module along with any dependencies.
  138. Suggested information to include here:
  139.  
  140.     any extra modules required for use
  141.     the minimum version of Perl required
  142.     if only works on certain operating systems
  143.  
  144.  
  145. =item MANIFEST.SKIP
  146.  
  147. A file full of regular expressions to exclude when using 'make
  148. manifest' to generate the MANIFEST.  These regular expressions
  149. are checked against each file path found in the distribution (so
  150. you're matching against "t/foo.t" not "foo.t").
  151.  
  152. Here's a sample:
  153.  
  154.     ~$          # ignore emacs and vim backup files
  155.     .bak$       # ignore manual backups
  156.     \#          # ignore CVS old revision files and emacs temp files
  157.  
  158. Since # can be used for comments, # must be escaped.
  159.  
  160. MakeMaker comes with a default MANIFEST.SKIP to avoid things like
  161. version control directories and backup files.  Specifying your own
  162. will override this default.
  163.  
  164.  
  165. =item bin/
  166.  
  167.  
  168. =back
  169.  
  170. =head1 SEE ALSO
  171.  
  172. L<perlmodstyle> gives stylistic help writing a module.
  173.  
  174. L<perlnewmod> gives more information about how to write a module.
  175.  
  176. There are modules to help you through the process of writing a module:
  177. L<ExtUtils::ModuleMaker>, L<Module::Install>, L<PAR>
  178.  
  179. =cut
  180.  
  181. 1;
  182.